Creating TeachText readme files containing Pictures in the past was something most people didn't like to do. Moreover many people didn't even know how to do it. It was a complex task, juggling resources, using ResEdit. So there weren't too many TeachText files with Pictures about. And yet, TeachText is an ideal instrument for readme documents and online-manuals of all kinds: it launches quickly, uses little memory and above all: everybody's got it.
So I decided to write an application to create TeachText files as easily as it is to create a MacWrite document, using cut&paste-like commands. The result was: TeachText Maker (TTM).
The first thing to do is write your text. You can do this using any word processor, editor or even TTM itself. Don't use fonts, styles ... , just write a plain (ASCII) text.Don't put in carriage returns in after each line, as TTM will wrap the text automatically.
You then save the file as a 'TEXT' file, without line breaks. (e.g. in MsWord choose 'save as...', click on file format and choose TEXT ONLY; in other wordprocessors, choose to put carriage returns after paragraphs only ). Or you could simply just cut and paste the text to TTM.
Use open to get the Textfile into TTM. As it is a textfile, you will get a message that it will open as untitled.
Now you can start preparing your Pictures using your favourite screen capture program, paint and/or draw program. Using Multifinder, you can make one picture at a time and directly cut and insert it into TTM, or else you could prepare all pictures at once, and keep them in your scrapbook for quick access.
Simply create the drawing as you like it. It is ready to be copied into the TTM document.
TIP : since teachtext doesn't support multiple fonts, you can create headings for the text in different fonts, by using drawings. Don't use any exotic fonts, because the user will probably not have these installed in his system.
Note : In the Macintosh technical notes there is an extra step mentioned: copy the drawings into a paint program and back to the draw program, to convert the drawing into a bitmap. Apple doesn't tell why you should do this. I 'discovered' two reasons:
(1) this way scrolling the pictures gives less 'flicker' .
(2) some special kinds of drawings, containing things like lines ending with arrows, don't appear correctly in TeachText(Maker). The only way to make them appear correctly is by converting the drawing into a bitmap.
There is one reason why you shouldn't convert the drawings: bitmaps look that much worse on a printer. So it's up to you to decide what you want: if your document will probably never be printed by the user, or your drawings don't appear correctly on screen, then convert the drawings to bitmaps, otherwise leave them as they are.
Create the painting as you like it. Then cut it out, using the lasso tool or equivalent. This way, you keep the painting as small as possible.
For some technical reasons, you must now paste the painting into a draw program, like Macdraw. This makes the Picture transparent (this in order to avoid thin white stripes running through the picture on some printers). You can check this transparency (*in TTM*) by typing through the picture like this example:
transparency test transparency test transparency test
if the letters get covered up by the picture, your draw program doesn't support this transparency conversion. Try and expreriment with other drawing programs.
Using a Paint or draw program, you are now ready to put the picture into your TTM document. Copy it from your draw program (using cut or copy) and go to TTM. Put the cursor on the place you'd like to insert the picture. Now select 'Insert Pict' from the utilities menu. The picture will be inserted and centred according to the window size.
Before I go any further, it is important to understand how things work under the hood. Selecting 'Show ¶' from the utilities menu should help clarify things a bit. If you are making your own document and have inserted a picture, you should see something like this:
Pictures and text are two completely separate entities for teachtext ( likewise for TTM as it uses the same principle). Pictures are not really inserted in the text, they just appear to be. Whenever you use 'insert pict' , an invisible character (called non-breaking space or sticky space) is inserted into the text. When using 'Show ¶' this character will appear as an 'i' in a box . This character is the sign for TTM the show the picture at that very position. Pictures are kept in an ordered list. So e.g. the fifth picture will be shown at the place of the fifth marker. Now here's where things can go wrong. You could accidentally delete the invisible character, causing the picture to be shown at the position of the next marker, messing things up. To avoid this, I suggest you do all editing using the 'Show ¶' option as on. If you still would accidentally delete the marker, do this: Go back to the place where the marker used to be, and press option-space bar. This re-inserts the marker. Everything should be all right now.
Warning: the marker, or sticky space, should ALWAYS be on the first position of a line. If not, it will not be recognized by TTM. This is done for speed reasons. By the contrary, TeachText will recognize any sticky space, whether or not in first position . If things look radically different when you look at the document using TeachText, investigate if you haven't inserted any characters before the markers.
As you see, extra carriage returns are inserted before and after the marker, to make room for the picture. Otherwise text and picture would be shown on top of each other. You can add or delete carriage returns as to make the picture show in the position you like .
After or during the pictures are inserted, you can go on editing. If you want to insert extra text before a picture, make sure your insertion point is really set before the maker. While typing, things might seem to become messy (like typing through the picture, picture doesn't scroll when you add carriage returns before it...) . Don't worry: If you leave the keyboard alone for about 3 seconds, TTM will refresh your screen, and (hopefully) make everything look fine again.
Always remember: text and pictures are two separate entities. Therefore, while editing, you should avoid selecting text ranges over pictures, e.g. for copying. The text will be copied, including the markers, but not the pictures.
To manipulate pictures, use the 'copy pict' and 'delete pict' menu items from the utilities menu.
Copy Pict: Go and put the cursor somewhere below the marker of the picture you want to copy and select 'Copy Pict'. TTM will scroll the picture to the top of the window( so that you can check if it is the right one) and copy it to the clipboard, where it's accessible for other TTM windows or other programs.
Delete Pict: Go and put the cursor somewhere below the marker of the picture you want to delete and select 'Delete Pict'. TTM will scroll the picture to the top of the window and ask you to confirm the deletion. Before deleting, the picture will be copied to the clipboard. Then the marker is removed, but the carriage returns, where the picture used to be, remain. You should remove these yourself.
Finally save your TTM document, and double click it, to launch TeachText. Print the document, to see how it looks. You may still want to change the document to avoid pictures from crossing printed-page boundaries.
That's it. Have fun !
First this : always use the 'Show ¶' option during editing to see what you're doing. This way you can avoid lots of trouble.
Problem : two pictures or a picture and text overlap
Solution : Insert extra carriage returns .
Problem : the pictures don't appear in the right places.
Solution: You have deleted a marker, or the maker is not on the first position of a line. Re-insert the marker, pressing option-space bar, or delete any preceding characters.
Problem : You've copied a text range to another program or another position, but the pictures don't appear.
Solution : TTM doesn't work like this. Use the utilities menu for picture manipulation. Don't select any text over picture boundaries, and make sure you don't copy markers.
Problem : the screen looks messy when editing.
Solution : stop typing for 3 seconds. Everything should be back in order.
Problem : TTM copies or deletes the wrong pictures.
Solution : TTM searches your text from the insertion point upwards to the first marker it meets. This will be the selected picture. TTM will scroll this picture into view to allow you to check if it's the right one. If there are no pictures, or there is a marker without a picture, TTM will do nothing.
Problem : the text gets cut off.
Solution: TTM and TeachText don't allow texts larger than 32000 characters. Make several smaller documents out of your big document. TTM also doesn't allow more than 512 pictures, but I guess that should be enough for most purposes .
Problem : Pictures look great in TTM but overlap with text in TeachText.
Solution : Teachtext uses the default application font. The default application font is stored in your PRAM. If you have changed this font (willing or unwilling) from geneva to something else, things will definitely go wrong. Zap your Pram (by holding down command-option-shift while opening your control panel).
This program is shareware. This means you can distribute it freely (see below), but if you use it, you must pay for it.
European users:
----------------
shareware fee:
* $10
* Eurocheques in Belgian Franks ONLY: BEF 300,-
to get a disk, add another $5 or BEF 150,-
Users outside Europe:
----------------------
shareware fee:
* $15
* please send NO cheques, as banks tend to charge substantial amounts of money for cashing foreign cheques. I do would like to keep some of the money you send me :-)
To get a disk add another $8
ShareWare User advantages
-----------------------------
* You are allowed to use any (future) version of TeachText Maker.
* Shareware users are personally notified of the release of the next version of TTM. You will be offered a disk at costprice.
* * At any time I might decide not to distribute the next version via the usual ShareWare channels, like this version, but exclusively and directly to registered users. If you want to be sure to get the next version, you'll have to become a registered shareware user !
You can spread this version to anybody you like (the more, the better) as long as you keep this in mind:
(1) it must be kept together with this unmodified document.
(2) You don't ask any money for it, except for possible distribution costs. People with commercial intentions should contact me to work something out.
Send shareware fees, bug reports, suggestions and comments to:
